≫ Добавление документов в таблицу

Добавление документов в таблицу реального времени

Если вы ищете информацию о добавлении документов в обычную таблицу, пожалуйста, обратитесь к разделу о добавлении данных из внешних хранилищ.

Добавление документов в реальном времени поддерживается только для таблиц Real-Time и percolate. Соответствующая SQL-команда, HTTP-эндпоинт или клиентские функции вставляют новые строки (документы) в таблицу с указанными значениями полей. Таблица не обязательно должна существовать до добавления в неё документов. Если таблица не существует, Manticore попытается создать её автоматически. Для получения дополнительной информации смотрите Автоматическая схема.

Вы можете вставить один или несколько документов с значениями для всех полей таблицы или только для части из них. В этом случае остальные поля будут заполнены значениями по умолчанию (0 для скалярных типов, пустая строка для текстовых типов).

В INSERT выражения в настоящее время не поддерживаются, поэтому значения должны быть указаны явно.

Поле/значение ID может быть опущено, так как таблицы RT и PQ поддерживают функциональность auto-id. Вы также можете использовать 0 в качестве значения id, чтобы принудительно сгенерировать автоматический ID. Строки с дублирующимися ID не будут перезаписаны с помощью INSERT. Для этого можно использовать REPLACE.

При использовании HTTP JSON протокола у вас есть два различных формата запроса на выбор: общий формат Manticore и формат, похожий на Elasticsearch. Оба формата продемонстрированы в примерах ниже.

Кроме того, при использовании формата запроса Manticore JSON имейте в виду, что узел doc обязателен, и все значения должны быть указаны внутри него.

‹›
  • SQL
  • JSON
  • Elasticsearch
  • PHP
  • Python
  • Python-asyncio
  • Javascript
  • Java
  • C#
  • Rust
📋

Общий синтаксис:

INSERT INTO <table name> [(column, ...)]
VALUES (value, ...)
[, (...)]
INSERT INTO products(title,price) VALUES ('Crossbody Bag with Tassel', 19.85);
INSERT INTO products(title) VALUES ('Crossbody Bag with Tassel');
INSERT INTO products VALUES (0,'Yellow bag', 4.95);
‹›
Response
Query OK, 1 rows affected (0.00 sec)
Query OK, 1 rows affected (0.00 sec)
Query OK, 1 rows affected (0.00 sec)

Автоматическая схема

ПРИМЕЧАНИЕ: Автоматическая схема требует Manticore Buddy. Если не работает, убедитесь, что Buddy установлен.

Manticore имеет механизм автоматического создания таблиц, который активируется, когда указанная в запросе вставки таблица ещё не существует. Этот механизм включён по умолчанию. Чтобы отключить его, установите auto_schema = 0 в разделе Searchd вашего конфигурационного файла Manticore.

По умолчанию все текстовые значения в разделе VALUES считаются типа text, за исключением значений, представляющих допустимые адреса электронной почты, которые обрабатываются как тип string.

Если вы попытаетесь вставить несколько строк с разными, несовместимыми типами значений для одного и того же поля, автоматическое создание таблицы будет отменено, и будет возвращено сообщение об ошибке. Однако, если разные типы значений совместимы, результирующий тип поля будет тем, который может вместить все значения. Некоторые автоматические преобразования типов данных, которые могут произойти, включают:

  • mva -> mva64
  • uint -> bigint -> float (это может привести к некоторой потере точности)
  • string -> text

Механизм автоматической схемы не поддерживает создание таблиц с векторными полями (полями типа float_vector), используемыми для поиска по сходству KNN (K-ближайших соседей). Чтобы использовать векторные поля в вашей таблице, вы должны явно создать таблицу с определением этих полей в схеме. Если вам нужно хранить векторные данные в обычной таблице без возможности поиска KNN, вы можете хранить их как JSON-массив, используя стандартный JSON-синтаксис, например: INSERT INTO table_name (vector_field) VALUES ('[1.0, 2.0, 3.0]').

Также будут распознаны и преобразованы в метки времени следующие форматы дат, в то время как все остальные форматы дат будут рассматриваться как строки:

  • %Y-%m-%dT%H:%M:%E*S%Z
  • %Y-%m-%d'T'%H:%M:%S%Z
  • %Y-%m-%dT%H:%M:%E*S
  • %Y-%m-%dT%H:%M:%s
  • %Y-%m-%dT%H:%M
  • %Y-%m-%dT%H

Имейте в виду, что HTTP-эндпоинт /bulk не поддерживает автоматическое создание таблиц (автоматическую схему). Только HTTP-эндпоинт /_bulk (похожий на Elasticsearch) и SQL-интерфейс поддерживают эту функцию.

‹›
  • SQL
  • JSON
📋
MySQL [(none)]> drop table if exists t; insert into t(i,f,t,s,j,b,m,mb) values(123,1.2,'text here','test@mail.com','{"a": 123}',1099511627776,(1,2),(1099511627776,1099511627777)); desc t; select * from t;
‹›
Response
--------------
drop table if exists t
--------------
Query OK, 0 rows affected (0.42 sec)
--------------
insert into t(i,f,t,j,b,m,mb) values(123,1.2,'text here','{"a": 123}',1099511627776,(1,2),(1099511627776,1099511627777))
--------------
Query OK, 1 row affected (0.00 sec)
--------------
desc t
--------------
+-------+--------+----------------+
| Field | Type   | Properties     |
+-------+--------+----------------+
| id    | bigint |                |
| t     | text   | indexed stored |
| s     | string |                |
| j     | json   |                |
| i     | uint   |                |
| b     | bigint |                |
| f     | float  |                |
| m     | mva    |                |
| mb    | mva64  |                |
+-------+--------+----------------+
8 rows in set (0.00 sec)
--------------
select * from t
--------------
+---------------------+------+---------------+----------+------+-----------------------------+-----------+---------------+------------+
| id                  | i    | b             | f        | m    | mb                          | t         | s             | j          |
+---------------------+------+---------------+----------+------+-----------------------------+-----------+---------------+------------+
| 5045949922868723723 |  123 | 1099511627776 | 1.200000 | 1,2  | 1099511627776,1099511627777 | text here | test@mail.com | {"a": 123} |
+---------------------+------+---------------+----------+------+-----------------------------+-----------+---------------+------------+
1 row in set (0.00 sec)

Автоматический ID

Manticore предоставляет функциональность автоматической генерации ID для столбца ID документов, вставляемых или заменяемых в таблице реального времени или Percolate таблице. Генератор создаёт уникальный ID для документа с некоторыми гарантиями, но его не следует рассматривать как автоинкрементный ID.

Гарантируется уникальность сгенерированного значения ID при следующих условиях:

  • Значение server_id текущего сервера находится в диапазоне от 0 до 127 и уникально среди узлов в кластере, либо используется значение по умолчанию, сгенерированное из MAC-адреса в качестве начального значения
  • Системное время не меняется для узла Manticore между перезапусками сервера
  • Авто ID генерируется менее 16 миллионов раз в секунду между перезапусками поискового сервера

Генератор авто ID создает 64-битное целое число для идентификатора документа и использует следующую схему:

  • Биты с 0 по 23 формируют счетчик, который увеличивается при каждом вызове генератора авто ID
  • Биты с 24 по 55 представляют Unix-временную метку запуска сервера
  • Биты с 56 по 63 соответствуют server_id

Эта схема гарантирует, что сгенерированный ID уникален среди всех узлов в кластере и что данные, вставленные в разные узлы кластера, не создают коллизий между узлами.

В результате первый ID из генератора, используемый для авто ID, НЕ равен 1, а является большим числом. Кроме того, поток документов, вставляемых в таблицу, может иметь не последовательные значения ID, если между вызовами происходят вставки в другие таблицы, так как генератор ID един для сервера и используется всеми его таблицами.

‹›
  • SQL
  • JSON
  • PHP
  • Python
  • Python-asyncio
  • Javascript
  • Java
  • C#
  • Rust
📋
INSERT INTO products(title,price) VALUES ('Crossbody Bag with Tassel', 19.85);
INSERT INTO products VALUES (0,'Yello bag', 4.95);
select * from products;
‹›
Response
+---------------------+-----------+---------------------------+
| id                  | price     | title                     |
+---------------------+-----------+---------------------------+
| 1657860156022587404 | 19.850000 | Crossbody Bag with Tassel |
| 1657860156022587405 |  4.950000 | Yello bag                 |
+---------------------+-----------+---------------------------+

UUID_SHORT множественная генерация ID

CALL UUID_SHORT(N)

Оператор CALL UUID_SHORT(N) позволяет сгенерировать N уникальных 64-битных ID за один вызов без вставки каких-либо документов. Это особенно полезно, когда необходимо предварительно сгенерировать ID в Manticore для использования в других системах или решениях для хранения. Например, вы можете сгенерировать авто-ID в Manticore, а затем использовать их в другой базе данных, приложении или рабочем процессе, обеспечивая согласованные и уникальные идентификаторы в разных средах.

‹›
  • Example
Example
📋
CALL UUID_SHORT(3)
‹›
Response
+---------------------+
| uuid_short()        |
+---------------------+
| 1227930988733973183 |
| 1227930988733973184 |
| 1227930988733973185 |
+---------------------+

Массовое добавление документов

Вы можете вставлять не только один документ в таблицу реального времени, но и сколько угодно. Абсолютно нормально вставлять партии из десятков тысяч документов в таблицу реального времени. Однако важно учитывать следующие моменты:

  • Чем больше партия, тем выше задержка каждой операции вставки
  • Чем больше партия, тем выше ожидаемая скорость индексации
  • Возможно, вам захочется увеличить значение max_packet_size, чтобы разрешить большие партии
  • Обычно каждая операция пакетной вставки считается одной транзакцией с гарантией атомарности, поэтому либо все новые документы окажутся в таблице одновременно, либо в случае сбоя ни один из них не будет добавлен. Подробнее об этом см. в примере "JSON" про пустую строку или переключение на другую таблицу.

Обратите внимание, что HTTP-эндпоинт /bulk не поддерживает автоматическое создание таблиц (auto schema). Только HTTP-эндпоинт /_bulk (подобный Elasticsearch) и SQL-интерфейс поддерживают эту функцию. HTTP-эндпоинт /_bulk (подобный Elasticsearch) позволяет включать имя кластера в имя таблицы в формате cluster_name:table_name.

Эндпоинт /_bulk принимает идентификаторы документов в том же формате, что и Elasticsearch, и вы также можете включать id внутри самого документа:

{ "index": { "table" : "products", "_id" : "1" } }
{ "title" : "Crossbody Bag with Tassel", "price": 19.85 }

или

{ "index": { "table" : "products" } }
{ "title" : "Crossbody Bag with Tassel", "price": 19.85, "id": "1" }

Передача чанками в /bulk

Эндпоинт /bulk (режим Manticore) поддерживает Chunked transfer encoding. Вы можете использовать это для передачи больших партий. Это:

  • снижает пиковое использование оперативной памяти, уменьшая риск OOM
  • уменьшает время отклика
  • позволяет обойти ограничение max_packet_size и передавать партии значительно больше максимального разрешенного значения max_packet_size (128 МБ), например, по 1 ГБ за раз.
‹›
  • SQL
  • JSON
  • Elasticsearch
  • PHP
  • Python
  • Python-asyncio
  • Javascript
  • Java
  • C#
  • Rust
📋

Для массовой вставки просто укажите больше документов в скобках после VALUES(). Синтаксис:

INSERT INTO <table name>[(column1, column2, ...)] VALUES(value1[, value2 , ...]), (...)

Опциональный список имен столбцов позволяет явно указать значения для некоторых столбцов, присутствующих в таблице. Все остальные столбцы будут заполнены значениями по умолчанию (0 для скалярных типов, пустая строка для строковых типов).

Например:

INSERT INTO products(title,price) VALUES ('Crossbody Bag with Tassel', 19.85), ('microfiber sheet set', 19.99), ('Pet Hair Remover Glove', 7.99);
‹›
Response
Query OK, 3 rows affected (0.01 sec)

В настоящее время выражения в INSERT не поддерживаются, и значения должны быть указаны явно.

Вставка значений мультизначных атрибутов (MVA)

Мультизначные атрибуты (MVA) вставляются как массивы чисел.

‹›
  • SQL
  • JSON
  • Elasticsearch
  • PHP
  • Python
  • Python-asyncio
  • Javascript
  • Java
  • C#
  • Rust
📋
INSERT INTO products(title, sizes) VALUES('shoes', (40,41,42,43));

Вставка JSON

Значение JSON может быть вставлено как экранированная строка (через SQL или JSON) или как JSON-объект (через JSON-интерфейс).

‹›
  • SQL
  • JSON
  • Elasticsearch
  • PHP
  • Python
  • Python-asyncio
  • Javascript
  • Java
  • C#
  • Rust
📋
INSERT INTO products VALUES (1, 'shoes', '{"size": 41, "color": "red"}');
Last modified: August 28, 2025